Hosting ipynb's on GitHub pages¶
WIP: so far, a pretty quickly thrown together jumble of notes
Preface¶
This is just 1 way to host an Rmd document. There are other options. This is just intended to show how to do it with GitHub pages, it is not claiming to GitHub pages to be the best route for all cases.
Step-by-step instructions¶
Make a notebook (ipynb file) you're proud of and want to share with the world!
Export the notebook to html
Name the html document
index.htmlGet the
index.htmlfile into your GitHub repo- Long term I recommend to find a Git+GitHub tutorial and learn how to interact with git. It's such a useful skill for so many different things!
- Short-term you can use the Add file button followed by clicking Upload files
Turn on GitHub pages for the repo by clicking:
- Settings
- Pages (under the Code and automation section in the sidebar)
- Find the dropdown menu in the Branch section of the page and select "main" (there's a chance you want to select "master")
- If you're new to GitHub there's probably only one option to choose, choose that one option that's not "None"
- Click the Save button
Wait!
Find your website online at:
https://<your-username>.github.io/<your-repo-name/- For example this repo is at https://github.com/AdamSpannbauer/hosting-ipynbs-with-GitHub-Pages/
- This shows my user name is
AdamSpannbauer - This shows my repo name is
hosting-Rmds-with-GitHub-Pages
- This shows my user name is
- It's published GitHub pages site can is https://adamspannbauer.github.io/hosting-ipynbs-with-GitHub-Pages/
- For example this repo is at https://github.com/AdamSpannbauer/hosting-ipynbs-with-GitHub-Pages/
Exporting the notebook to HTML¶
Export menu¶
- On
jupyterlab- File > Save and Export Notebook As... > HTML - On the classic jupyter notebook editor - File > Download as > HTML
- On vscode - Export > HTML
- find the export button on the menu above your notebook (this menu has + Code, + Markdown, Run All, etc). You might have to click a ... button to find Export.
Exporting with nbconvert¶
The nbconvert tool can be used to create an index.html file and allow you to have some more customization options.
!jupyter nbconvert example.ipynb --no-input --to html --output index.html
[NbConvertApp] Converting notebook example.ipynb to html [NbConvertApp] WARNING | Alternative text is missing on 1 image(s). [NbConvertApp] Writing 3942544 bytes to index.html
The --no-input flag will make it so code doesn't appear in the output html file - remove --no-input if you want to show your code. If you just want to show just one or two python cell's code, you might consider code formatting in a markdown cell. There are other options available for toggling code cell visibility.
You can use jupyterlab themes to apply CSS theming to the output:
!pip install jupyterlab
!pip install jupyterlab_miami_nights
!jupyter nbconvert example.ipynb --no-input --to html --output index.html --theme jupyterlab_miami_nights
[NbConvertApp] Converting notebook example.ipynb to html [NbConvertApp] WARNING | Alternative text is missing on 1 image(s). [NbConvertApp] Writing 4340727 bytes to index.html
Putting contents in your notebook¶
Inlcuding a matplotlib made plot¶
Including a plotly made plot¶
To inlcude plotly graphics you need to initialize their notebook mode:
Sizing can be controlled to fixed pixel width & height.